home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 1.iso / dist / fw_ddd.idb / usr / freeware / info / ddd.info-5.z / ddd.info-5
Text File  |  2001-10-09  |  50KB  |  1,268 lines
  1. This is ddd.info, produced by makeinfo version 4.0 from ddd.texi.
  2.  
  3. INFO-DIR-SECTION Miscellaneous
  4. START-INFO-DIR-ENTRY
  5. * DDD: (ddd).                     The Data Display Debugger.
  6. END-INFO-DIR-ENTRY
  7.  
  8. DDD is a graphical front-end for GDB and other command-line debuggers.
  9.  
  10. This is the First Edition, 2001-02-01, of `Debugging with DDD' for DDD
  11. Version 3.3.1.
  12.  
  13. Copyright (C) 2001 UniversitΣt Passau
  14. Lehrstuhl fⁿr Software-Systeme
  15. Innstra▀e 33
  16. D-94032 Passau
  17. GERMANY
  18.  
  19. Distributed by
  20. Free Software Foundation, Inc.
  21. 59 Temple Place - Suite 330
  22. Boston, MA 02111-1307
  23. USA
  24.  
  25. DDD and this manual are available via the DDD WWW page
  26. (http://www.gnu.org/software/ddd/).
  27.  
  28.    Permission is granted to copy, distribute and/or modify this document
  29. under the terms of the GNU Free Documentation License, Version 1.1 or
  30. any later version published by the Free Software Foundation; with no
  31. Invariant Sections, no Front-Cover Texts and no Back-Cover Texts.  A
  32. copy of the license is included in the section entitled "GNU Free
  33. Documentation License".
  34.  
  35.    Send questions, comments, suggestions, etc. to <ddd@gnu.org>.
  36. Send bug reports to <bug-ddd@gnu.org>.
  37. 
  38. File: ddd.info,  Node: Hardware-Assisted Breakpoints,  Prev: Editing all Breakpoints,  Up: Breakpoints
  39.  
  40. Hardware-Assisted Breakpoints
  41. -----------------------------
  42.  
  43.    Using GDB, a few more commands related to breakpoints can be invoked
  44. through the debugger console:
  45.  
  46. `hbreak POSITION'
  47.      Sets a hardware-assisted breakpoint at POSITION.  This command
  48.      requires hardware support and some target hardware may not have
  49.      this support.  The main purpose of this is EPROM/ROM code
  50.      debugging, so you can set a breakpoint at an instruction without
  51.      changing the instruction.
  52.  
  53. `thbreak POS'
  54.      Set a temporary hardware-assisted breakpoint at POS.
  55.  
  56.    *Note Setting breakpoints: (gdb)Setting breakpoints, for details.
  57.  
  58. 
  59. File: ddd.info,  Node: Watchpoints,  Next: Interrupting,  Prev: Breakpoints,  Up: Stopping
  60.  
  61. Watchpoints
  62. ===========
  63.  
  64.    You can make the program stop as soon as some variable value
  65. changes, or when some variable is read or written.  This is called
  66. "setting a watchpoint on a variable".(1)
  67.  
  68.    Watchpoints have much in common with breakpoints: in particular, you
  69. can enable and disable them.  You can also set conditions, ignore
  70. counts, and commands to be executed when a watched variable changes its
  71. value.
  72.  
  73.    Please note: on architectures without special watchpoint support,
  74. watchpoints currently make the program execute two orders of magnitude
  75. more slowly.  This is so because the inferior debugger must interrupt
  76. the program after each machine instruction in order to examine whether
  77. the watched value has changed.  However, this delay can be well worth it
  78. to catch errors when you have no clue what part of your program is the
  79. culprit.
  80.  
  81. * Menu:
  82.  
  83. * Setting Watchpoints::
  84. * Editing Watchpoint Properties::
  85. * Editing all Watchpoints::
  86. * Deleting Watchpoints::
  87.  
  88.    ---------- Footnotes ----------
  89.  
  90.    (1) Watchpoints are available in GDB and some DBX variants only.  In
  91. XDB, a similar feature is available via XDB "assertions"; see the XDB
  92. documentation for details.
  93.  
  94. 
  95. File: ddd.info,  Node: Setting Watchpoints,  Next: Editing Watchpoint Properties,  Up: Watchpoints
  96.  
  97. Setting Watchpoints
  98. -------------------
  99.  
  100.    If the variable name is visible, click with _mouse button 1_ on the
  101. variable name.  The variable name is copied to the argument field.
  102. Otherwise, enter the variable name in the argument field.  Click on the
  103. `Watch' button to set a watchpoint there.
  104.  
  105.    Using GDB and JDB 1.2, you can set different types of watchpoints.
  106. Click and hold _mouse button 1_ on the `Watch' button to get a menu.
  107.  
  108. 
  109. File: ddd.info,  Node: Editing Watchpoint Properties,  Next: Editing all Watchpoints,  Prev: Setting Watchpoints,  Up: Watchpoints
  110.  
  111. Editing Watchpoint Properties
  112. -----------------------------
  113.  
  114.    To change the properties of a watchpoint, enter the name of the
  115. watched variable in the argument field.  Click and hold _mouse button
  116. 1_ on the `Watch' button and select `Watchpoint Properties'.
  117.  
  118.    The Watchpoint Properties panel has the same functionality as the
  119. Breakpoint Properties panel (*note Editing Breakpoint Properties::).  As
  120. an additional feature, you can click on `Print' to see the current
  121. value of a watched variable.
  122.  
  123. 
  124. File: ddd.info,  Node: Editing all Watchpoints,  Next: Deleting Watchpoints,  Prev: Editing Watchpoint Properties,  Up: Watchpoints
  125.  
  126. Editing all Watchpoints
  127. -----------------------
  128.  
  129.    To view and edit all watchpoints at once, select `Data =>
  130. Watchpoints'.  This will popup the "Watchpoint Editor" which displays
  131. the state of all watchpoints.
  132.  
  133.    The Watchpoint Editor has the same functionality as the Breakpoint
  134. Editor (*note Editing all Breakpoints::).  As an additional feature, you
  135. can click on `Print' to see the current value of a watched variable.
  136.  
  137. 
  138. File: ddd.info,  Node: Deleting Watchpoints,  Prev: Editing all Watchpoints,  Up: Watchpoints
  139.  
  140. Deleting Watchpoints
  141. --------------------
  142.  
  143.    To delete a watchpoint, enter the name of the watched variable in the
  144. argument field and click the `Unwatch' button.
  145.  
  146. 
  147. File: ddd.info,  Node: Interrupting,  Next: Stopping X Programs,  Prev: Watchpoints,  Up: Stopping
  148.  
  149. Interrupting
  150. ============
  151.  
  152.    If the program is already running (*note Running::), you can
  153. interrupt it any time by clicking the `Interrupt' button or typing <ESC>
  154. in a DDD window.(1)  Using GDB, this is equivalent to sending a
  155. `SIGINT' (Interrupt) signal.
  156.  
  157.    `Interrupt' and <ESC> also interrupt a running debugger command,
  158. such as printing data.
  159.  
  160.    ---------- Footnotes ----------
  161.  
  162.    (1) If <Ctrl+C> is not bound to `Copy' (*note Customizing the Edit
  163. Menu::), you can also use <Ctrl+C> to interrupt the running program.
  164.  
  165. 
  166. File: ddd.info,  Node: Stopping X Programs,  Prev: Interrupting,  Up: Stopping
  167.  
  168. Stopping X Programs
  169. ===================
  170.  
  171.    If your program is a modal X application, DDD may interrupt it while
  172. it has grabbed the mouse pointer, making further interaction
  173. impossible--your X display will be unresponsive to any user actions.
  174.  
  175.    By default, DDD will check after each interaction whether the
  176. pointer is grabbed.  If the pointer is grabbed, DDD will continue the
  177. debugged program such that you can continue to use your X display.
  178.  
  179.    This is how this feature works: When the program stops, DDD checks
  180. for input events such as keyboard or mouse interaction.  If DDD does
  181. not receive any event within the next 5 seconds, DDD checks whether the
  182. mouse pointer is grabbed by attempting to grab and ungrab it.  If this
  183. attempt fails, then DDD considers the pointer grabbed.
  184.  
  185.    Unfortunately, DDD cannot determine the program that grabbed the
  186. pointer--it may be the debugged program, or another program.
  187. Consequently, you have another 10 seconds to cancel continuation before
  188. DDD continues the program automatically.
  189.  
  190.    There is one situation where this fails: if you lock your X display
  191. while DDD is running, then DDD will consider a resulting pointer grab
  192. as a result of running the program--and automatically continue
  193. execution of the debugged program.  Consequently, you can turn off this
  194. feature via `Edit => Preferences => General => Continue Automatically
  195. when Mouse Pointer is Frozen'.
  196.  
  197. * Menu:
  198.  
  199. * Customizing Grab Checking::
  200.  
  201. 
  202. File: ddd.info,  Node: Customizing Grab Checking,  Up: Stopping X Programs
  203.  
  204. Customizing Grab Checking
  205. -------------------------
  206.  
  207.    The grab checks are controlled by the following resources:
  208.  
  209.  - Resource: checkGrabs (class CheckGrabs)
  210.      If this is `on' (default), DDD will check after each interaction
  211.      whether the pointer is grabbed.  If this is so, DDD will
  212.      automatically continue execution of debugged program.
  213.  
  214.  - Resource: checkGrabDelay (class CheckGrabDelay)
  215.      The time to wait (in ms) after a debugger command before checking
  216.      for a grabbed pointer.  If DDD sees some pointer event within this
  217.      delay, the pointer cannot be grabbed and an explicit check for a
  218.      grabbed pointer is unnecessary.  Default is `5000', or 5 seconds.
  219.  
  220.  - Resource: grabAction (class grabAction)
  221.      The action to take after having detected a grabbed mouse pointer.
  222.      This is a list of newline-separated commands.  Default is `cont',
  223.      meaning to continue the debuggee.  Other possible choices include
  224.      `kill' (killing the debuggee) or `quit' (exiting DDD).
  225.  
  226.  - Resource: grabActionDelay (class grabActionDelay)
  227.      The time to wait (in ms) before taking an action due to having
  228.      detected a grabbed pointer.  During this delay, a working dialog
  229.      pops up telling the user about imminent execution of the grab
  230.      action (see the `grabAction' resource, above).  If the pointer
  231.      grab is released within this delay, the working dialog pops down
  232.      and no action is taken.  This is done to exclude pointer grabs
  233.      from sources other than the debugged program (including DDD).
  234.      Default is `10000', or 10 seconds.
  235.  
  236. 
  237. File: ddd.info,  Node: Running,  Next: Examining Data,  Prev: Stopping,  Up: Top
  238.  
  239. Running the Program
  240. *******************
  241.  
  242.    You may start the debugged program with its arguments, if any, in an
  243. environment of your choice.  You may redirect your program's input and
  244. output, debug an already running process, or kill a child process.
  245.  
  246. * Menu:
  247.  
  248. * Starting Program Execution::
  249. * Using the Execution Window::
  250. * Attaching to a Process::
  251. * Program Stop::
  252. * Resuming Execution::
  253. * Continuing Somewhere Else::
  254. * Stack::
  255. * Undoing Program Execution::
  256. * Threads::
  257. * Signals::
  258. * Killing the Program::
  259.  
  260. 
  261. File: ddd.info,  Node: Starting Program Execution,  Next: Using the Execution Window,  Up: Running
  262.  
  263. Starting Program Execution
  264. ==========================
  265.  
  266.    To start execution of the debugged program, select `Program => Run'.
  267. You will then be prompted for the arguments to pass to your program.
  268. You can either select from a list of previously used arguments or enter
  269. own arguments in the text field.  Afterwards, press the `Run' button to
  270. start execution with the selected arguments.
  271.  
  272.    To run your program again, with the same arguments, select `Program
  273. => Run Again' or press the `Run' button on the command tool.  You may
  274. also enter `run', followed by arguments at the debugger prompt instead.
  275.  
  276.    When you click on `Run', your program begins to execute immediately.
  277. *Note Stopping::, for a discussion of how to arrange for your program
  278. to stop.  Once your program has stopped, you may call functions in your
  279. program to examine data.  *Note Examining Data::, for details.
  280.  
  281.    If the modification time of your symbol file has changed since the
  282. last time GDB read its symbols, GDB discards its symbol table, and
  283. reads it again.  When it does this, GDB and DDD try to retain your
  284. current debugger state, such as breakpoints.
  285.  
  286. * Menu:
  287.  
  288. * Arguments::                   Your program's arguments.
  289. * Environment::                 Your program's environment.
  290. * Working Directory::           Your program's directory.
  291. * Input/Output::                Your program's I/O.
  292.  
  293. 
  294. File: ddd.info,  Node: Arguments,  Next: Environment,  Up: Starting Program Execution
  295.  
  296. Your Program's Arguments
  297. ------------------------
  298.  
  299.    The arguments to your program are specified by the arguments of the
  300. `run' command, as composed in `Program => Run'.
  301.  
  302.    In GDB, the arguments are passed to a shell, which expands wildcard
  303. characters and performs redirection of I/O, and thence to your program.
  304. Your `SHELL' environment variable (if it exists) specifies what shell
  305. GDB uses.  If you do not define `SHELL', GDB uses `/bin/sh'.
  306.  
  307.    If you use another inferior debugger, the exact semantics on how the
  308. arguments are interpreted depend on the inferior debugger you are using.
  309. Normally, the shell is used to pass the arguments, so that you may use
  310. normal conventions (such as wildcard expansion or variable substitution)
  311. in describing the arguments.
  312.  
  313. 
  314. File: ddd.info,  Node: Environment,  Next: Working Directory,  Prev: Arguments,  Up: Starting Program Execution
  315.  
  316. Your Program's Environment
  317. --------------------------
  318.  
  319.    Your program normally inherits its environment from the inferior
  320. debugger, which again inherits it from DDD, which again inherits it
  321. from its parent process (typically the shell or desktop).
  322.  
  323.    In GDB, you can use the commands `set environment' and `unset
  324. environment' to change parts of the environment that affect your
  325. program.  *Note Your program's environment: (gdb)Your program's
  326. environment, for details.
  327.  
  328.    The following environment variables are set by DDD:
  329.  
  330. `DDD'
  331.      Set to a string indicating the DDD version.  By testing whether
  332.      `DDD' is set, a debuggee (or inferior debugger) can determine
  333.      whether it was invoked by DDD.
  334.  
  335. `TERM'
  336.      Set to `dumb', the DDD terminal type.  This is set for the
  337.      inferior debugger only.(1)
  338.  
  339. `TERMCAP'
  340.      Set to `' (none), the DDD terminal capabilities.
  341.  
  342. `PAGER'
  343.      Set to `cat', the preferred DDD pager.
  344.  
  345.    The inferior debugger, in turn, might also set or unset some
  346. environment variables.
  347.  
  348.    ---------- Footnotes ----------
  349.  
  350.    (1) If the debuggee runs in a separate execution window, the
  351. debuggee's `TERM' value is set according to the `termType' resource;
  352. *Note Customizing the Execution Window::, for details.
  353.  
  354. 
  355. File: ddd.info,  Node: Working Directory,  Next: Input/Output,  Prev: Environment,  Up: Starting Program Execution
  356.  
  357. Your Program's Working Directory
  358. --------------------------------
  359.  
  360.    Your program normally inherits its working directory from the
  361. inferior debugger, which again inherits it from DDD, which again
  362. inherits it from its parent process (typically the shell or desktop).
  363.  
  364.    You can change the working directory of the inferior debugger via
  365. `File => Change Directory' or via the `cd' command of the inferior
  366. debugger.
  367.  
  368. 
  369. File: ddd.info,  Node: Input/Output,  Prev: Working Directory,  Up: Starting Program Execution
  370.  
  371. Your Program's Input and Output
  372. -------------------------------
  373.  
  374.    By default, the program you run under DDD does input and output to
  375. the debugger console.  Normally, you can redirect your program's input
  376. and/or output using "shell redirections" with the arguments--that is,
  377. additional arguments like `< INPUT' or `> OUTPUT'.  You can enter these
  378. shell redirections just like other arguments (*note Arguments::).
  379.  
  380.    _Warning:_ While input and output redirection work, you cannot use
  381. pipes to pass the output of the program you are debugging to another
  382. program; if you attempt this, DDD may wind up debugging the wrong
  383. program.  *Note Attaching to a Process::, for an alternative.
  384.  
  385.    If command output is sent to the debugger console, it is impossible
  386. for DDD to distinguish between the output of the debugged program and
  387. the output of the inferior debugger.
  388.  
  389.    Program output that confuses DDD includes:
  390.  
  391.    * Primary debugger prompts (e.g. `(gdb) ', `(dbx) ' or `(ladebug) ')
  392.  
  393.    * Secondary debugger prompts (e.g. `>')
  394.  
  395.    * Confirmation prompts (e.g. `(y or n) ')
  396.  
  397.    * Prompts for more output (e.g. `Press RETURN to continue')
  398.  
  399.    * Display output (e.g. `$pc = 0x1234')
  400.  
  401.    If your program outputs any of these strings, you may encounter
  402. problems with DDD mistaking them for debugger output.  These problems
  403. can easily be avoided by redirecting program I/O, for instance to the
  404. separate execution window (*note Using the Execution Window::).
  405.  
  406.    If the inferior debugger changes the default TTY settings, for
  407. instance through a `stty' command in its initialization file, DDD may
  408. also become confused.  The same applies to debugged programs which
  409. change the default TTY settings.
  410.  
  411.    The behavior of the debugger console can be controlled using the
  412. following resource:
  413.  
  414.  - Resource: lineBufferedConsole (class LineBuffered)
  415.      If this is `on' (default), each line from the inferior debugger is
  416.      output on each own, such that the final line is placed at the
  417.      bottom of the debugger console.  If this is `off', all lines are
  418.      output as a whole.  This is faster, but results in a random
  419.      position of the last line.
  420.  
  421. 
  422. File: ddd.info,  Node: Using the Execution Window,  Next: Attaching to a Process,  Prev: Starting Program Execution,  Up: Running
  423.  
  424. Using the Execution Window
  425. ==========================
  426.  
  427.    By default, input and output of your program go to the debugger
  428. console.  As an alternative, DDD can also invoke an "execution window",
  429. where the program terminal input and output is shown.(1)
  430.  
  431.    To activate the execution window, select `Program => Run in
  432. Execution Window'.
  433.  
  434.    Using the execution window has an important side effect: The output
  435. of your program no longer gets intermixed with the output of the
  436. inferior debugger.  This makes it far easier for DDD to parse the
  437. debugger output correctly.  *Note Debugger Communication::, for details
  438. on the `bufferGDBOutput' resource.
  439.  
  440.    The execution window is opened automatically as soon as you start the
  441. debugged program.  While the execution window is active, DDD redirects
  442. the standard input, output, and error streams of your program to the
  443. execution window.  Note that the device `/dev/tty' still refers to the
  444. debugger console, _not_ the execution window.
  445.  
  446.    You can override the DDD stream redirection by giving alternate
  447. redirection operations as arguments.  For instance, to have your program
  448. read from FILE, but to write to the execution window, invoke your
  449. program with `< FILE' as argument.  Likewise, to redirect the standard
  450. error output to the debugger console, use `2> /dev/tty' (assuming the
  451. inferior debugger and/or your UNIX shell support standard error
  452. redirection).
  453.  
  454. * Menu:
  455.  
  456. * Customizing the Execution Window::
  457.  
  458.    ---------- Footnotes ----------
  459.  
  460.    (1) The execution window is not available in JDB.
  461.  
  462. 
  463. File: ddd.info,  Node: Customizing the Execution Window,  Up: Using the Execution Window
  464.  
  465. Customizing the Execution Window
  466. --------------------------------
  467.  
  468.    You can customize the DDD execution window and use a different TTY
  469. command.  The command is set by `Edit => Preferences => Helpers =>
  470. Execution Window':
  471.  
  472.  - Resource: termCommand (class TermCommand)
  473.      The command to invoke for the execution window--a TTY emulator
  474.      that shows the input/output of the debugged program.  A Bourne
  475.      shell command to run in the separate TTY is appended to this
  476.      string.  The string `@FONT@' is replaced by the name of the fixed
  477.      width font used by DDD.  A simple value is
  478.  
  479.           Ddd*termCommand: xterm -fn @FONT@ -e /bin/sh -c
  480.  
  481.    You can also set the terminal type:
  482.  
  483.  - Resource: termType (class TermType)
  484.      The terminal type provided by the `termCommand' resource--that is,
  485.      the value of the `TERM' environment variable to be passed to the
  486.      debugged program.  Default: `xterm'.
  487.  
  488.    Whether the execution window is active or not, as set by `Program =>
  489. Run in Execution Window', is saved using this resource:
  490.  
  491.  - Resource: separateExecWindow (class Separate)
  492.      If `on', the debugged program is executed in a separate execution
  493.      window.  If `off' (default), the debugged program is executed in
  494.      the console window.
  495.  
  496. 
  497. File: ddd.info,  Node: Attaching to a Process,  Next: Program Stop,  Prev: Using the Execution Window,  Up: Running
  498.  
  499. Attaching to a Running Process
  500. ==============================
  501.  
  502.    If the debugged program is already running in some process, you can
  503. "attach" to this process (instead of starting a new one with `Run').(1)
  504.  
  505.    To attach DDD to a process, select `File => Attach to Process'.  You
  506. can now choose from a list of processes.  Then, press the `Attach'
  507. button to attach to the specified process.
  508.  
  509.    The first thing DDD does after arranging to debug the specified
  510. process is to stop it. You can examine and modify an attached process
  511. with all the DDD commands that are ordinarily available when you start
  512. processes with `Run'. You can insert breakpoints; you can step and
  513. continue; you can modify storage. If you would rather the process
  514. continue running, you may use `Continue' after attaching DDD to the
  515. process.
  516.  
  517.    When using `Attach to Process', you should first use `Open Program'
  518. to specify the program running in the process and load its symbol table.
  519.  
  520.    When you have finished debugging the attached process, you can use
  521. the `File => Detach Process' to release it from DDD control.  Detaching
  522. the process continues its execution.  After `Detach Process', that
  523. process and DDD become completely independent once more, and you are
  524. ready to attach another process or start one with `Run'.
  525.  
  526.    You can customize the list of processes shown by defining an
  527. alternate command to list processes.  See `Edit => Preferences =>
  528. Helpers => List Processes'; *Note Customizing Attaching to Processes::,
  529. for details.
  530.  
  531. * Menu:
  532.  
  533. * Customizing Attaching to Processes::
  534.  
  535.    ---------- Footnotes ----------
  536.  
  537.    (1) JDB, PYDB, and Perl do not support attaching the debugger to
  538. running processes.
  539.  
  540. 
  541. File: ddd.info,  Node: Customizing Attaching to Processes,  Up: Attaching to a Process
  542.  
  543. Customizing Attaching to Processes
  544. ----------------------------------
  545.  
  546.    When attaching to a process (*note Attaching to a Process::), DDD
  547. uses a `ps' command to get the list of processes.  This command is
  548. defined by the `psCommand' resource.
  549.  
  550.  - Resource: psCommand (class PsCommand)
  551.      The command to get a list of processes.  Usually `ps'.  Depending
  552.      on your system, useful alternate values include `ps -ef' and `ps
  553.      ux'.  The first line of the output must either contain a `PID'
  554.      title, or each line must begin with a process ID.
  555.  
  556.      Note that the output of this command is filtered by DDD; a process
  557.      is only shown if it can be attached to.  The DDD process itself as
  558.      well as the process of the inferior debugger are suppressed, too.
  559.  
  560. 
  561. File: ddd.info,  Node: Program Stop,  Next: Resuming Execution,  Prev: Attaching to a Process,  Up: Running
  562.  
  563. Program Stops
  564. =============
  565.  
  566.    After the program has been started, it runs until one of the
  567. following happens:
  568.  
  569.    * A breakpoint is reached (*note Breakpoints::).
  570.  
  571.    * A watched value changes (*note Watchpoints::).
  572.  
  573.    * The program is interrupted (*note Interrupting::).
  574.  
  575.    * A signal is received (*note Signals::).
  576.  
  577.    * Execution completes.
  578.  
  579.    DDD shows the current program status in the debugger console.  The
  580. current execution position is highlighted by an arrow.
  581.  
  582.    If `Edit => Preferences => General => Uniconify When Ready' is set,
  583. DDD automatically deiconifies itself when the program stops.  This way,
  584. you can iconify DDD during a lengthy computation and have it uniconify
  585. as soon as the program stops.
  586.  
  587. 
  588. File: ddd.info,  Node: Resuming Execution,  Next: Continuing Somewhere Else,  Prev: Program Stop,  Up: Running
  589.  
  590. Resuming Execution
  591. ==================
  592.  
  593. Continuing
  594. ----------
  595.  
  596.    To resume execution, at the current execution position, click on the
  597. `Continue' button.  Any breakpoints set at the current execution
  598. position are bypassed.
  599.  
  600. Stepping one Line
  601. -----------------
  602.  
  603.    To execute just one source line, click on the `Step' button.  The
  604. program is executed until control reaches a different source line, which
  605. may be in a different function.  Then, the program is stopped and
  606. control returns to DDD.
  607.  
  608.    _Warning_: If you use the `Step' button while control is within a
  609. function that was compiled without debugging information, execution
  610. proceeds until control reaches a function that does have debugging
  611. information.  Likewise, it will not step into a function which is
  612. compiled without debugging information.  To step through functions
  613. without debugging information, use the `Stepi' button (*note Machine
  614. Code Execution::).
  615.  
  616.    In GDB, the `Step' button only stops at the first instruction of a
  617. source line.  This prevents the multiple stops that used to occur in
  618. switch statements, for loops, etc.  `Step' continues to stop if a
  619. function that has debugging information is called within the line.
  620.  
  621.    Also, the `Step' in GDB only enters a subroutine if there is line
  622. number information for the subroutine.  Otherwise it acts like the
  623. `Next' button.
  624.  
  625. Continuing to the Next Line
  626. ---------------------------
  627.  
  628.    To continue to the next line in the current function, click on the
  629. `Next' button.  This is similar to `Step', but any function calls
  630. appearing within the line of code are executed without stopping.
  631.  
  632.    Execution stops when control reaches a different line of code at the
  633. original stack level that was executing when you clicked on `Next'.
  634.  
  635. Continuing Until Here
  636. ---------------------
  637.  
  638.    To continue running until a specific location is reached, use the
  639. `Continue Until Here' facility from the line popup menu.  *Note
  640. Temporary Breakpoints::, for a discussion.
  641.  
  642. Continuing Until a Greater Line is Reached
  643. ------------------------------------------
  644.  
  645.    To continue until a greater line in the current function is reached,
  646. click on the `Until' button.  This is useful to avoid single stepping
  647. through a loop more than once.
  648.  
  649.    `Until' is like `Next', except that when `Until' encounters a jump,
  650. it automatically continues execution until the program counter is
  651. greater than the address of the jump.
  652.  
  653.    This means that when you reach the end of a loop after single
  654. stepping though it, `until' makes your program continue execution until
  655. it exits the loop.  In contrast, clicking on `Next' at the end of a
  656. loop simply steps back to the beginning of the loop, which forces you to
  657. step through the next iteration.
  658.  
  659.    `Until' always stops your program if it attempts to exit the current
  660. stack frame.
  661.  
  662.    `Until' works by means of single instruction stepping, and hence is
  663. slower than continuing until a breakpoint is reached.
  664.  
  665. Continuing Until Function Returns
  666. ---------------------------------
  667.  
  668.    To continue running until the current function returns, use the
  669. `Finish' button.  The returned value (if any) is printed.
  670.  
  671. 
  672. File: ddd.info,  Node: Continuing Somewhere Else,  Next: Stack,  Prev: Resuming Execution,  Up: Running
  673.  
  674. Continuing at a Different Address
  675. =================================
  676.  
  677.    Ordinarily, when you continue your program, you do so at the place
  678. where it stopped.  You can instead continue at an address of your own
  679. choosing.
  680.  
  681.    The most common occasion to use this feature is to back up--perhaps
  682. with more breakpoints set-over a portion of a program that has already
  683. executed, in order to examine its execution in more detail.
  684.  
  685.    To set the execution position to the current location, use `Set
  686. Execution Position' from the breakpoint popup menu.  This item is also
  687. accessible by pressing and holding the `Break/Clear' button.(1)
  688.  
  689.    As a quicker alternative, you can also press _mouse button 1_ on the
  690. arrow and drag it to a different location.(2)
  691.  
  692.    Moving the execution position does not change the current stack
  693. frame, or the stack pointer, or the contents of any memory location or
  694. any register other than the program counter.
  695.  
  696.    Some inferior debuggers (notably GDB) allow you to set the new
  697. execution position into a different function from the one currently
  698. executing.  This may lead to bizarre results if the two functions
  699. expect different patterns of arguments or of local variables.  For this
  700. reason, moving the execution position requests confirmation if the
  701. specified line is not in the function currently executing.
  702.  
  703.    After moving the execution position, click on `Continue' to resume
  704. execution.
  705.  
  706.    ---------- Footnotes ----------
  707.  
  708.    (1) JDB, PYDB, and Perl do not support altering the execution
  709. position.
  710.  
  711.    (2) When glyphs are disabled (*note Customizing Source::), dragging
  712. the execution position is not possible.  Set the execution position
  713. explicitly instead.
  714.  
  715. 
  716. File: ddd.info,  Node: Stack,  Next: Undoing Program Execution,  Prev: Continuing Somewhere Else,  Up: Running
  717.  
  718. Examining the Stack
  719. ===================
  720.  
  721.    When your program has stopped, the first thing you need to know is
  722. where it stopped and how it got there.
  723.  
  724.    Each time your program performs a function call, information about
  725. the call is generated.  That information includes the location of the
  726. call in your program, the arguments of the call, and the local
  727. variables of the function being called.  The information is saved in a
  728. block of data called a "stack frame".  The stack frames are allocated
  729. in a region of memory called the "call stack".
  730.  
  731.    When your program stops, the DDD commands for examining the stack
  732. allow you to see all of this information.
  733.  
  734.    One of the stack frames is "selected" by DDD and many DDD commands
  735. refer implicitly to the selected frame.  In particular, whenever you
  736. ask DDD for the value of a variable in your program, the value is found
  737. in the selected frame.  There are special DDD commands to select
  738. whichever frame you are interested in.
  739.  
  740. * Menu:
  741.  
  742. * Frames::                      Callers and callees.
  743. * Backtraces::                  And you may ask yourself, `how did I get here?'
  744. * Selecting a frame::           Moving up and down.
  745.  
  746. 
  747. File: ddd.info,  Node: Frames,  Next: Backtraces,  Up: Stack
  748.  
  749. Stack Frames
  750. ------------
  751.  
  752.    The call stack is divided up into contiguous pieces called "stack
  753. frames", or "frames" for short; each frame is the data associated with
  754. one call to one function.  The frame contains the arguments given to
  755. the function, the function's local variables, and the address at which
  756. the function is executing.
  757.  
  758.    When your program is started, the stack has only one frame, that of
  759. the function `main'.  This is called the "initial" frame or the
  760. "outermost" frame.  Each time a function is called, a new frame is
  761. made.  Each time a function returns, the frame for that function
  762. invocation is eliminated.  If a function is recursive, there can be
  763. many frames for the same function.  The frame for the function in which
  764. execution is actually occurring is called the "innermost" frame.  This
  765. is the most recently created of all the stack frames that still exist.
  766.  
  767.    Inside your program, stack frames are identified by their addresses.
  768. A stack frame consists of many bytes, each of which has its own
  769. address; each kind of computer has a convention for choosing one byte
  770. whose address serves as the address of the frame.  Usually this address
  771. is kept in a register called the "frame pointer register" while
  772. execution is going on in that frame.
  773.  
  774.    GDB assigns numbers to all existing stack frames, starting with zero
  775. for the innermost frame, one for the frame that called it, and so on
  776. upward.  These numbers do not really exist in your program; they are
  777. assigned by GDB to give you a way of designating stack frames in GDB
  778. commands.
  779.  
  780. 
  781. File: ddd.info,  Node: Backtraces,  Next: Selecting a frame,  Prev: Frames,  Up: Stack
  782.  
  783. Backtraces
  784. ----------
  785.  
  786.    DDD provides a "backtrace window" showing a summary of how your
  787. program got where it is.  It shows one line per frame, for many frames,
  788. starting with the currently executing frame (frame zero), followed by
  789. its caller (frame one), and on up the stack.
  790.  
  791.    To enable the backtrace window, select `Status => Backtrace'.
  792.  
  793.    Using GDB, each line in the backtrace shows the frame number and the
  794. function name.  The program counter value is also shown--unless you use
  795. the GDB command `set print address off'.  The backtrace also shows the
  796. source file name and line number, as well as the arguments to the
  797. function.  The program counter value is omitted if it is at the
  798. beginning of the code for that line number.
  799.  
  800. 
  801. File: ddd.info,  Node: Selecting a frame,  Prev: Backtraces,  Up: Stack
  802.  
  803. Selecting a Frame
  804. -----------------
  805.  
  806.    Most commands for examining the stack and other data in your program
  807. work on whichever stack frame is selected at the moment.  Here are the
  808. commands for selecting a stack frame.(1)
  809.  
  810.    In the backtrace window, you can _select_ an arbitrary frame to move
  811. from one stack frame to another.  Just click on the desired frame.
  812.  
  813.    The `Up' button selects the function that called the current
  814. one--that is, it moves one frame up.
  815.  
  816.    The `Down' button selects the function that was called by the
  817. current one--that is, it moves one frame down.
  818.  
  819.    You can also directly type the `up' and `down' commands at the
  820. debugger prompt.  Typing <Ctrl+Up> and <Ctrl+Down>, respectively, will
  821. also move you through the stack.
  822.  
  823.    `Up' and `Down' actions can be undone via `Edit => Undo'.
  824.  
  825.    ---------- Footnotes ----------
  826.  
  827.    (1) Perl does not allow changing the current stack frame.
  828.  
  829. 
  830. File: ddd.info,  Node: Undoing Program Execution,  Next: Threads,  Prev: Stack,  Up: Running
  831.  
  832. "Undoing" Program Execution
  833. ===========================
  834.  
  835.    If you take a look at the `Edit => Undo' menu item after an
  836. execution command, you'll find that DDD offers you to undo execution
  837. commands just as other commands.  Does this mean that DDD allows you to
  838. go backwards in time, undoing program execution as well as undoing any
  839. side-effects of your program?
  840.  
  841.    Sorry--we must disappoint you.  DDD cannot undo what your program
  842. did.  (After a little bit of thought, you'll find that this would be
  843. impossible in general.)  However, DDD can do something different: it
  844. can show _previously recorded states_ of your program.
  845.  
  846.    After "undoing" an execution command (via `Edit => Undo', or the
  847. `Undo' button), the execution position moves back to the earlier
  848. position and displayed variables take their earlier values.  Your
  849. program state is in fact unchanged, but DDD gives you a _view_ on the
  850. earlier state as recorded by DDD.
  851.  
  852.    In this so-called "historic mode", most normal DDD commands that
  853. would query further information from the program are disabled, since
  854. the debugger cannot be queried for the earlier state.  However, you can
  855. examine the current execution position, or the displayed variables.
  856. Using `Undo' and `Redo', you can move back and forward in time to
  857. examine how your program got into the present state.
  858.  
  859.    To let you know that you are operating in historic mode, the
  860. execution arrow gets a dashed-line appearance (indicating a past
  861. position); variable displays also come with dashed lines.  Furthermore,
  862. the status line informs you that you are seeing an earlier program
  863. state.
  864.  
  865.    Here's how historic mode works: each time your program stops, DDD
  866. collects the current execution position and the values of displayed
  867. variables.  Backtrace, thread, and register information is also
  868. collected if the corresponding dialogs are open.  When "undoing" an
  869. execution command, DDD updates its view from this collected state
  870. instead of querying the program.
  871.  
  872.    If you want to collect this information without interrupting your
  873. program--within a loop, for instance--you can place a breakpoint with
  874. an associated `cont' command (*note Breakpoint Commands::).  When the
  875. breakpoint is hit, DDD will stop, collect the data, and execute the
  876. `cont' command, resuming execution.  Using a later `Undo', you can step
  877. back and look at every single loop iteration.
  878.  
  879.    To leave historic mode, you can use `Redo' until you are back in the
  880. current program state.  However, any DDD command that refers to program
  881. state will also leave historic mode immediately by applying to the
  882. current program state instead.  For instance, `Up' leaves historic mode
  883. immediately and selects an alternate frame in the restored current
  884. program state.
  885.  
  886.    If you want to see the history of a specific variable, as recorded
  887. during program stops, you can enter the DDD command
  888.  
  889.      graph history NAME
  890.  
  891.    This returns a list of all previously recorded values of the variable
  892. NAME, using array syntax.  Note that NAME must have been displayed at
  893. earlier program stops in order to record values.
  894.  
  895. 
  896. File: ddd.info,  Node: Threads,  Next: Signals,  Prev: Undoing Program Execution,  Up: Running
  897.  
  898. Examining Threads
  899. =================
  900.  
  901.    In some operating systems, a single program may have more than one
  902. _thread_ of execution.  The precise semantics of threads differ from
  903. one operating system to another, but in general the threads of a single
  904. program are akin to multiple processes--except that they share one
  905. address space (that is, they can all examine and modify the same
  906. variables).  On the other hand, each thread has its own registers and
  907. execution stack, and perhaps private memory.
  908.  
  909.    For debugging purposes, DDD lets you display the list of threads
  910. currently active in your program and lets you select the _current
  911. thread_--the thread which is the focus of debugging.  DDD shows all
  912. program information from the perspective of the current thread.(1)
  913.  
  914.    To view all currently active threads in your program, select `Status
  915. => Threads'.  The current thread is highlighted.  Select any thread to
  916. make it the current thread.
  917.  
  918.    Using JDB, additional functionality is available:
  919.  
  920.    * Select a _thread group_ to switch between viewing all threads and
  921.      the threads of the selected thread group;
  922.  
  923.    * Click on `Suspend' to suspend execution of the selected threads;
  924.  
  925.    * Click on `Resume' to resume execution of the selected threads.
  926.  
  927.    For more information on threads, see the JDB and GDB documentation
  928. (*note Debugging programs with multiple threads: (gdb)Threads.).
  929.  
  930.    ---------- Footnotes ----------
  931.  
  932.    (1) Currently, threads are supported in GDB and JDB only.
  933.  
  934. 
  935. File: ddd.info,  Node: Signals,  Next: Killing the Program,  Prev: Threads,  Up: Running
  936.  
  937. Handling Signals
  938. ================
  939.  
  940.    A signal is an asynchronous event that can happen in a program.  The
  941. operating system defines the possible kinds of signals, and gives each
  942. kind a name and a number.  For example, in UNIX, `SIGINT' is the signal
  943. a program gets when you type an interrupt; `SIGSEGV' is the signal a
  944. program gets from referencing a place in memory far away from all the
  945. areas in use; `SIGALRM' occurs when the alarm clock timer goes off
  946. (which happens only if your program has requested an alarm).
  947.  
  948.    Some signals, including `SIGALRM', are a normal part of the
  949. functioning of your program.  Others, such as `SIGSEGV', indicate
  950. errors; these signals are _fatal_ (kill your program immediately) if
  951. the program has not specified in advance some other way to handle the
  952. signal.  `SIGINT' does not indicate an error in your program, but it is
  953. normally fatal so it can carry out the purpose of the interrupt: to
  954. kill the program.
  955.  
  956.    GDB has the ability to detect any occurrence of a signal in your
  957. program.  You can tell GDB in advance what to do for each kind of
  958. signal.
  959.  
  960.    Normally, DDD is set up to ignore non-erroneous signals like
  961. `SIGALRM' (so as not to interfere with their role in the functioning of
  962. your program) but to stop your program immediately whenever an error
  963. signal happens.  In DDD, you can view and edit these settings via
  964. `Status => Signals'.
  965.  
  966.    `Status => Signals' pops up a panel showing all the kinds of signals
  967. and how GDB has been told to handle each one.  The settings available
  968. for each signal are:
  969.  
  970. `Stop'
  971.      If set, GDB should stop your program when this signal happens.
  972.      This also implies `Print' being set.
  973.  
  974. `Print'
  975.      If set, GDB should print a message when this signal happens.
  976.  
  977.      If unset, GDB should not mention the occurrence of the signal at
  978.      all.  This also implies `Stop' being unset.
  979.  
  980. `Pass'
  981.      If set, GDB should allow your program to see this signal; your
  982.      program can handle the signal, or else it may terminate if the
  983.      signal is fatal and not handled.
  984.  
  985.      If unset, GDB should not allow your program to see this signal.
  986.  
  987.    The entry `All Signals' is special.  Changing a setting here affects
  988. _all signals at once_--except those used by the debugger, typically
  989. `SIGTRAP' and `SIGINT'.
  990.  
  991.    To undo any changes, use `Edit => Undo'.  The `Reset' button
  992. restores the saved settings.
  993.  
  994.    When a signal stops your program, the signal is not visible until you
  995. continue.  Your program sees the signal then, if `Pass' is in effect
  996. for the signal in question _at that time_.  In other words, after GDB
  997. reports a signal, you can change the `Pass' setting in `Status =>
  998. Signals' to control whether your program sees that signal when you
  999. continue.
  1000.  
  1001.    You can also cause your program to see a signal it normally would not
  1002. see, or to give it any signal at any time.  The `Send' button will
  1003. resume execution where your program stopped, but immediately give it the
  1004. signal shown.
  1005.  
  1006.    On the other hand, you can also prevent your program from seeing a
  1007. signal.  For example, if your program stopped due to some sort of memory
  1008. reference error, you might store correct values into the erroneous
  1009. variables and continue, hoping to see more execution; but your program
  1010. would probably terminate immediately as a result of the fatal signal
  1011. once it saw the signal.  To prevent this, you can resume execution using
  1012. `Commands => Continue Without Signal'.
  1013.  
  1014.    `Edit => Save Options' does not save changed signal settings, since
  1015. changed signal settings are normally useful within specific projects
  1016. only.  Instead, signal settings are saved with the current session,
  1017. using `File => Save Session As'.
  1018.  
  1019. 
  1020. File: ddd.info,  Node: Killing the Program,  Prev: Signals,  Up: Running
  1021.  
  1022. Killing the Program
  1023. ===================
  1024.  
  1025.    You can kill the process of the debugged program at any time using
  1026. the `Kill' button.
  1027.  
  1028.    Killing the process is useful if you wish to debug a core dump
  1029. instead of a running process.  GDB ignores any core dump file while
  1030. your program is running.
  1031.  
  1032.    The `Kill' button is also useful if you wish to recompile and relink
  1033. your program, since on many systems it is impossible to modify an
  1034. executable file while it is running in a process.  In this case, when
  1035. you next click on `Run', GDB notices that the file has changed, and
  1036. reads the symbol table again (while trying to preserve your current
  1037. debugger state).
  1038.  
  1039. 
  1040. File: ddd.info,  Node: Examining Data,  Next: Machine-Level Debugging,  Prev: Running,  Up: Top
  1041.  
  1042. Examining Data
  1043. **************
  1044.  
  1045.    DDD provides several means to examine data.
  1046.  
  1047.    * The quickest way to examine variables is to move the pointer on an
  1048.      occurrence in the source text.  The value is displayed in the
  1049.      source line; after a second, a popup window (called "value tip")
  1050.      shows the variable value.  This is useful for quick examination of
  1051.      several simple values.
  1052.  
  1053.    * If you want to refer to variable values at a later time, you can
  1054.      "print" the value in the debugger console.  This allows for
  1055.      displaying and examining larger data structures.
  1056.  
  1057.    * If you want to examine complex data structures, you can "display"
  1058.      them graphically in the data window.  Displays remain effective
  1059.      until you delete them; they are updated each time the program
  1060.      stops.  This is useful for large dynamic structures.
  1061.  
  1062.    * If you want to examine arrays of numeric values, you can "plot"
  1063.      them graphically in a separate plot window.  The plot is updated
  1064.      each time the program stops.  This is useful for large numeric
  1065.      arrays.
  1066.  
  1067.    * Using GDB or DBX, you can also "examine memory contents" in any of
  1068.      several formats, independently of your program's data types.
  1069.  
  1070. * Menu:
  1071.  
  1072. * Value Tips::                  Just move the pointer on a variable.
  1073. * Printing Values::             Printing a value in the debugger console.
  1074. * Displaying Values::           Displaying structures as graphs.
  1075. * Plotting Values::             Displaying values as plots.
  1076. * Examining Memory::            Low-level memory examination.
  1077.  
  1078. 
  1079. File: ddd.info,  Node: Value Tips,  Next: Printing Values,  Up: Examining Data
  1080.  
  1081. Showing Simple Values using Value Tips
  1082. ======================================
  1083.  
  1084.    To display the value of a simple variable, move the mouse pointer on
  1085. its name.  After a second, a small window (called "value tip") pops up
  1086. showing the value of the variable pointed at.  The window disappears as
  1087. soon as you move the mouse pointer away from the variable.  The value is
  1088. also shown in the status line.
  1089.  
  1090.    You can disable value tips via `Edit => Preferences => General =>
  1091. Automatic display of variable values as popup tips'.
  1092.  
  1093.    You can disable displaying variable values in the status line via
  1094. `Edit => Preferences => General => Automatic display of variable values
  1095. in the status line'.
  1096.  
  1097.    These customizations are tied to the following resources:
  1098.  
  1099.  - Resource: valueTips (class Tips)
  1100.      Whether value tips are enabled (`on', default) or not (`off').
  1101.      Value tips affect DDD performance and may be distracting for some
  1102.      experienced users.
  1103.  
  1104.  - Resource: valueDocs (class Docs)
  1105.      Whether the display of variable values in the status line is
  1106.      enabled (`on', default) or not (`off').
  1107.  
  1108.    You can turn off value tips via `Edit => Preferences => General =>
  1109. Automatic Display of Variable Values'.
  1110.  
  1111. 
  1112. File: ddd.info,  Node: Printing Values,  Next: Displaying Values,  Prev: Value Tips,  Up: Examining Data
  1113.  
  1114. Printing Simple Values in the Debugger Console
  1115. ==============================================
  1116.  
  1117.    The variable value can also be printed in the debugger console,
  1118. making it available for future operations.  To print a variable value,
  1119. select the desired variable by clicking _mouse button 1_ on its name.
  1120. The variable name is copied to the argument field.  By clicking the
  1121. `Print' button, the value is printed in the debugger console.  The
  1122. printed value is also shown in the status line.
  1123.  
  1124.    As a shorter alternative, you can simply press _mouse button 3_ on
  1125. the variable name and select the `Print' item from the popup menu.
  1126.  
  1127.    In GDB, the `Print' button generates a `print' command, which has
  1128. several more options.  *Note Examining Data: (gdb)Data, for
  1129. GDB-specific expressions, variables, and output formats.
  1130.  
  1131. 
  1132. File: ddd.info,  Node: Displaying Values,  Next: Plotting Values,  Prev: Printing Values,  Up: Examining Data
  1133.  
  1134. Displaying Complex Values in the Data Window
  1135. ============================================
  1136.  
  1137.    To explore complex data structures, you can "display" them
  1138. permanently in the _data window_.  The data window displays selected
  1139. data of your program, showing complex data structures graphically.  It
  1140. is updated each time the program stops.
  1141.  
  1142. * Menu:
  1143.  
  1144. * Display Basics::              How to create, manipulate, and delete displays.
  1145. * Arrays::                      Special functions for arrays.
  1146. * Assignment::                  Setting variable values.
  1147. * Examining Structures::        Dereferencing pointers and other references.
  1148. * Customizing Displays::        Data Themes.
  1149. * Layouting the Graph::         Automatic layout.
  1150. * Printing the Graph::          Printing on paper.
  1151.  
  1152. 
  1153. File: ddd.info,  Node: Display Basics,  Next: Arrays,  Up: Displaying Values
  1154.  
  1155. Display Basics
  1156. --------------
  1157.  
  1158.    This section discusses how to create, manipulate, and delete
  1159. displays.  The essentials are:
  1160.  
  1161.    * Click on `Display' to display the variable in `()'.
  1162.  
  1163.    * Click on a display to select it.
  1164.  
  1165.    * Click on `Undisplay' to delete the selected display.
  1166.  
  1167. * Menu:
  1168.  
  1169. * Creating Single Displays::
  1170. * Selecting Displays::
  1171. * Showing and Hiding Details::
  1172. * Rotating Displays::
  1173. * Displaying Local Variables::
  1174. * Displaying Program Status::
  1175. * Refreshing the Data Window::
  1176. * Placement::
  1177. * Clustering::
  1178. * Creating Multiple Displays::
  1179. * Editing all Displays::
  1180. * Deleting Displays::
  1181.  
  1182. 
  1183. File: ddd.info,  Node: Creating Single Displays,  Next: Selecting Displays,  Up: Display Basics
  1184.  
  1185. Creating Single Displays
  1186. ........................
  1187.  
  1188.    To create a new display showing a specific variable, select the
  1189. variable by clicking _mouse button 1_ on its name.  The variable name is
  1190. copied to the argument field.  By clicking the `Display' button, a new
  1191. display is created in the data window.  The data window opens
  1192. automatically as soon as you create a display.
  1193.  
  1194.    As a shorter alternative, you can simply press _mouse button 3_ on
  1195. the variable name and select `Display' from the popup menu.
  1196.  
  1197.    As an even faster alternative, you can also double-click on the
  1198. variable name.
  1199.  
  1200.    As another alternative, you may also enter the expression to be
  1201. displayed in the argument field and press the `Display' button.
  1202.  
  1203.    Finally, you may also type in a command at the debugger prompt:
  1204.  
  1205.      graph display EXPR [clustered] [at (X, Y)]
  1206.          [dependent on DISPLAY] [[now or] when in SCOPE]
  1207.  
  1208.    This command creates a new display showing the value of the
  1209. expression EXPR.  The optional parts have the following meaning:
  1210.  
  1211. `clustered'
  1212.      If given, the new display is created in a cluster.  *Note
  1213.      Clustering::, for a discussion.
  1214.  
  1215. `at (X, Y)'
  1216.      If given, the new display is created at the position (X, Y).
  1217.      Otherwise, a default position is assigned.
  1218.  
  1219. `dependent on DISPLAY'
  1220.      If given, an edge from the display numbered or named _display_ to
  1221.      the new display is created.  Otherwise, no edge is created.  *Note
  1222.      Dependent Values::, for details.
  1223.  
  1224. `when in SCOPE'
  1225. `now or when in SCOPE'
  1226.      If `when in' is given, the display creation is "deferred" until
  1227.      execution reaches the given SCOPE (a function name, as in the
  1228.      backtrace output).
  1229.  
  1230.      If `now or when in' is given, DDD first attempts to create the
  1231.      display immediately.  The display is deferred only if display
  1232.      creation fails.
  1233.  
  1234.      If neither `when in' suffix nor `now or when in' suffix is given,
  1235.      the display is created immediately.
  1236.  
  1237. 
  1238. File: ddd.info,  Node: Selecting Displays,  Next: Showing and Hiding Details,  Prev: Creating Single Displays,  Up: Display Basics
  1239.  
  1240. Selecting Displays
  1241. ..................
  1242.  
  1243.    Each display in the data window has a _title bar_ containing the
  1244. _display number_ and the displayed expression (the _display name_).
  1245. Below the title, the _display value_ is shown.
  1246.  
  1247.    You can select single displays by clicking on them with _mouse
  1248. button 1_.
  1249.  
  1250.    You can _extend_ an existing selection by pressing the <Shift> key
  1251. while selecting.  You can also _toggle_ an existing selection by
  1252. pressing the <Shift> key while selecting already selected displays.
  1253.  
  1254.    Single displays may also be selected by using the arrow keys <Up>,
  1255. <Down>, <Left>, and <Right>.
  1256.  
  1257.    _Multiple displays_ are selected by pressing and holding _mouse
  1258. button 1_ somewhere on the window background.  By moving the pointer
  1259. while holding the button, a selection rectangle is shown; all displays
  1260. fitting in the rectangle are selected when mouse button 1 is released.
  1261.  
  1262.    If the <Shift> key is pressed while selecting, the existing
  1263. selection is _extended_.
  1264.  
  1265.    By double-clicking on a display title, the display itself and all
  1266. connected displays are automatically selected.
  1267.  
  1268.